dcemriS4 (version 0.20.2)

Audit Trails: Facilitate the Creation and Modification of Audit Trails

Description

Facilitate the creation and modification of audit trails for NIfTI class objects.

Usage

dcemri.info(type)
enableAuditTrail()
newAuditTrail()
niftiExtensionToAuditTrail(nim, workingDirectory = NULL,
                           filename = NULL, call = NULL)
niftiAuditTrailToExtension(nim, workingDirectory = NULL,
                           filename = NULL, call = NULL)
niftiAuditTrailSystemNode(type="system-info",
                          workingDirectory = NULL,
                          filename = NULL, call = NULL)
niftiAuditTrailSystemNodeEvent(trail, type = NULL, call = NULL,
                               workingDirectory = NULL,
                               filename = NULL, comment=NULL)
niftiAuditTrailCreated(history = NULL, call = NULL,
                       workingDirectory = NULL, filename = NULL)
niftiAuditTrailEvent(trail, type = NULL, call = NULL,
                     comment = NULL)
getLastCallWithName(functionName)

Arguments

nim

is an object of class niftiAuditTrail or can be converted to such.

workingDirectory

The working directory associated with the filename.

filename

The filename associated with the nifti object.

call

A call, function name in the call-stack or a string.

type

An identifier to add some meaning to the event.

trail

The XMLAbstractNode representing the audit trail or the niftiAuditTrail object with a trail that will be amended.

comment

Some textual comment

history

An XMLAbstractNode to store historical events for inclusion in the trail.

functionName

The name of a function on the call stack.

Details

The function dcemri.info is used to find the ecode or the XML namespace relevant to the audit trail.

The function enableAuditTrail is called as the package loads to switch on the audit trail functionality and declare the class niftiAuditTrail. Should you wish to prevent the audit trail functionality loading, you should set the option NIfTI.audit.trail to FALSE. Manually calling the function enableAuditTrail will override this setting and switch on the functionality.

The function newAuditTrail returns an XMLAbstractNode representing the root node of an audit trail. This is mostly intended as an internal function.

The function niftiExtensionToAuditTrail takes an object representing a NIfTI object, casts it as a niftiAuditTrail and checks if there is an extension (a niftiExtensionSection) with ecode equal to dcemri.info("ecode"); i.e. has a extension with data representing a serialized audit trail. The function will then strip the object of this extension parsing the serialized edata into an audit trail and adding a read event to the trail.

The function niftiAuditTrailToExtension takes a niftiAuditTrail and returns a niftiExtensionSection with edata containing the serialized form of the audit trail after adding a saved event to the trail.

The function niftiAuditTrailSystemNodeEvent adds an element with name equal to type to the trail. It uses the niftiAuditTrailSystemNode function to create the node. The function niftiAuditTrailSystemNode is an internal function creating an XMLAbstractNode element with name type and attributes giving information about the R system and library. The filename and call will also be added as attributes if available.

The function niftiAuditTrailEvent adds an element with name event to the trail. The arguments type, filename, call are added as attributes and the comment is the text value of the element.

The function niftiAuditTrailCreated will create a new audit trail containing a system node element created with the child history with the contents history. If the last element of the history given is an event with type="processing", then this node will be removed from the history and its call attribute will be used as the value of the call attribute on the created node.

The function getLastCallWithName will search the call stack for a call of the function functionName, returning last call to that function if possible. It will default to the call of the function which called the function which called getLastCallWithName if there was no such call (and if there was no such call it will return the call of itself).

Examples

## A good example of the use of these functions is shown by this
## wrapper function which takes a function fun(nim, ...) returning
## lists of arrays which are nifti-ized using as(...)
wrapper <- function(functionToWrap, nameOfCallingFunction, nim, ...) {
  if (!is(nim, "nifti")) 
    nim <- as(nim, "nifti")
  
  if (is(nim, "niftiAuditTrail")) {
    ## This will force as(...) to set the call which created the
    ## results to the calling function's call rather than
    ## as(result, nifti) as it would otherwise do
    nim@trail <- niftiAuditTrailEvent(nim@trail, "processing",
                                      nameOfCallingFunction)
  }
  
  result <- functionToWrap(nim, ...)
  as(result, "nifti") <- nim
  return(result)
}

## An example of how wrapper is used follows:
functionToWrap <- function(ignored, x, y) {
  return (array(1, dim=c(x,y)))
}

## The niftiized form
niftiizedForm <- function(nim,...) {
  return(wrapper(functionToWrap, "niftiizedForm", nim, ...))
}

## compare the trails
if (getOption("NIfTI.audit.trail")) {
  print((as.nifti(functionToWrap(nifti(), 4, 4), nifti()))@trail)
  print(niftiizedForm(nifti(), 4, 4)@trail)
}